<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Panel</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>Panel</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p>Panel is a widget that mimics the functionality of a regular OS window. It is similar to Overlay, with added functionality to support modality, event listeners on which to autohide and autofocus, header/footer button support and a custom stylesheet. Panel does not have any implementation code of it's own. It implements a set of extensions that provide certain sets of functionality. The <a href="../widget/widget-build.html">"Creating Custom Widget Classes"</a> example shows how you can use these extensions to build classes which mix and match some of the above features.</p>
</div>


<h2 id="getting-started">Getting Started</h2>

<p>
To include the source files for Panel and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>

<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>

<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
YUI().use(&#x27;panel&#x27;, function (Y) {
    &#x2F;&#x2F; Panel is available and ready for use. Add implementation
    &#x2F;&#x2F; code here.
});</pre>


<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global object</a>.
</p>


<h2 id="default">Creating a Panel</h2>
<p>This simple example will create a Panel with default functionality. By default, a Panel is rendered with a "Close" button added to the header, with modality enabled, and will be hidden if the "esc" key or "Close" button is pressed. Clicking anywhere outside the panel will bring back focus to the panel.</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode: &quot;#myPanelContent&quot;,
        width: 400,
        centered: true
    });

    panel.render();

});</pre>


<h2 id="modality">Modal Panel</h2>
<p>A Panel is not modal by default. This functionality can be changed through the "modal" attribute, either during instantiation or later through the set() method.</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode: &quot;#myPanelContent&quot;,
        width: 400,
        modal: true &#x2F;&#x2F;make a modal panel
    });

    panel.render();
    &#x2F;&#x2F;optionally, we could have written panel.set(&#x27;modal&#x27;, true);

});</pre>


<p>Panels can be nested in one another, and have different modal behavior. For instance, a modal panel may launch a non-modal panel on top of it. The <a href="http://yuilibrary.com/yui/docs/api/Widget.html"><code>WidgetModality</code></a> extension takes care of nesting behavior so no extra code is required for the implementer. Refer to the examples for more information.</p>

<h2 id="events">Choosing when to focus and hide</h2>

<p>By default, a Panel will return focus to itself if anything else on the page receives focus or is clicked. On the other hand, clicking the "close" button, or pressing the "esc" key will hide it. Both of these options can be configured as needed through the "hideOn" and "focusOn" attributes.</p>

<p>The following code snippet shows how to change the default "hide" behavior. Instead of hiding when the "esc" key is pressed, the Panel hides whenever something outside it's bounding box is pressed, or when a certain element on the page (with an id of <code>anotherNode</code>) is clicked.</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode: &quot;#myPanelContent&quot;,
        width: 400,
        centered: true,
        modal:false,

        &#x2F;&#x2F;The hideOn Attribute takes an array of objects, with a required property &quot;eventName&quot;
        &#x2F;&#x2F;and two optional properties &quot;node&quot;, and &quot;keyCode&quot;
        hideOn: [
                    
                    {
                        &#x2F;&#x2F;When we don&#x27;t specify a node, it defaults to the boundingbox of this panel instance
                        eventName: &quot;clickoutside&quot;
                    },
                    {
                        &#x2F;&#x2F;This listens to click events on the node that was specified
                        node: Y.one(&quot;#anotherNode&quot;),
                        eventName:&quot;click&quot;
                    }
                ]
    });

    panel.render();

});</pre>


<p>Similarly, the "focusOn" attribute can be changed to configure the default focus behavior</p>
<pre class="code prettyprint">var panel = new Y.Panel({
    srcNode: &quot;#myPanelContent&quot;,
    width: 400,
    centered: true,
    modal:false,

    &#x2F;&#x2F;The focusOn Attribute takes an array of objects, with a required property &quot;eventName&quot;
    &#x2F;&#x2F;and two optional properties &quot;node&quot;, and &quot;keyCode&quot;
    focusOn: [
                
                {
                    &#x2F;&#x2F;When we don&#x27;t specify a node, it defaults to the boundingbox of this panel instance
                    eventName: &quot;clickoutside&quot;
                },
                {
                    &#x2F;&#x2F;This listens to click events on the node that was specified
                    node: Y.one(&quot;#anotherNode&quot;),
                    eventName:&quot;click&quot;
                }
            ]
});

panel.render();

});</pre>


<p>To simply get rid of the default behavior, we could just set the "focusOn" and "hideOn" attributes to empty arrays.</p>

<h2 id="buttons">Header/Footer Button Support</h2>

<p>Panel supports header/footer buttons through the <a href="http://yuilibrary.com/yui/docs/api/WidgetButtons.html"><code>WidgetButtons</code></a> and <a href="http://yuilibrary.com/yui/docs/api/Widget-StdMod.html"><code>Widget-StdMod</code></a> extensions. By default, it comes with a "close" button represented by the "x" in the top-right corner of the header. As a developer, you can easily add/remove buttons to the header or the footer, change the style of existing buttons, or change the markup that is used to render the buttons.</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {
    
    var doSomethingElse = function() { ... };

    var panel = new Y.Panel({
        srcNode: &quot;#myPanelContent&quot;,
        width: 400,
        centered: true,

        &#x2F;&#x2F;make changes to the buttons through the &quot;buttons&quot; attribute, which takes an array of objects
        buttons: [
                    

                    {
                        &#x2F;&#x2F;each object has a &quot;value&quot; property, which can be text or an HTML string,
                        value: &quot;Okay&quot;,

                        &#x2F;&#x2F; &quot;defaultFn&quot; which takes the function that should be executed on a click event
                        defaultFn: function(e) {
                            e.preventDefault();
                            panel.hide();
                            doSomethingElse();
                        },

                        &#x2F;&#x2F; &quot;section&quot; which tells where to render the button and should be Y.WidgetStdMod.HEADER, or Y.WidgetStdMod.FOOTER
                        section: Y.WidgetStdMod.FOOTER

                        &#x2F;&#x2F;plus an optional &quot;href&quot; property if you are linking to an URL
                    }
                 ]
    });

    panel.render();

});</pre>


<p>If you want to append buttons to the ones that are already present within the panel, you can use the <code>addButton()</code> method.

<pre class="code prettyprint">var cancelButton = {
    value: &quot;Cancel&quot;,
    defaultFn: function(e) { 
        e.preventDefault(); 
        cancelActions(); 
    },
    section: Y.WidgetStdMod.FOOTER &#x2F;&#x2F;we could also write &quot;header&quot;, &quot;footer&quot; or Y.WidgetStdMod.HEADER here.
};

panel.addButton(cancelButton);</pre>


<h2 id="notes">Note regarding older browsers</h2>

<p>Panel is tested across the A-grade browser set according to the <a href="http://developer.yahoo.com/yui/articles/gbs/" alt="Graded Browser Support">GBS Browser Test Baseline</a> as of July 2011.</p>

<p>However, developers implementing Panel and other components which rely on z-index support in IE6 and IE7 should be aware of the concept of <a href="https://developer.mozilla.org/en/Understanding_CSS_z-index/Stacking_context_example_2" alt="Stacking Context in IE">stacking context</a>. Essentially, when setting the z-index of the widget, you should ensure that the widget's parent does not have a lower z-index.</p>
</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#default">Creating a Panel</a>
</li>
<li>
<a href="#modality">Modal Panel</a>
</li>
<li>
<a href="#events">Choosing when to focus and hide</a>
</li>
<li>
<a href="#buttons">Header/Footer Button Support</a>
</li>
<li>
<a href="#notes">Note regarding older browsers</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Shows how to instantiate multiple Panel instances, and use nested modality to interact with a Datatable.">
                                        <a href="panel-form.html">Creating a modal form</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Shows how to create a panel that animates as it is shown and hidden">
                                        <a href="panel-animate.html">Creating an animated panel</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            

            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
